docs: catalog guard authorizes renames and commits by their tables (platform #758) - #44

Summary

Platform docs for egret-data/platform#758 (merge 1e0a3cf8, "authorize renames and commits by the tables they change"). egret's Iceberg catalog guard now reads the body of a rename and a commit and decides on the tables they actually change. It also requires a catalog-level grant for a recursive namespace drop, refuses remote S3 signing, and matches grant names case-insensitively, the way the catalog resolves them. This PR documents what each operation needs from a Catalog Client's grants, the refusals (Iceberg JSON, 403/400/413), and an upgrade note. It also fixes the text that said the mount exposes no signer endpoint, and adds KI-311 to KI-314. No row described these holes, so none is closed.

Changes

• Catalog detail (control-plane/catalogs/catalog-detail.md): a new subsection under Roles & grants, What each operation needs (#what-each-operation-needs):
  • what a catalog, namespace and table grant cover (a namespace grant does not cover child namespaces);
  • a table of operations: load/list, create or stage-create, single-table commit (the body's identifier if present, otherwise the path's table; a view commit by its path), multi-table commit (every table; one miss refuses the whole commit), rename (source as a drop, destination as a create; a table grant on the destination name is not enough), drop, recursive namespace drop (catalog-level write or manage), remote signing (403 whatever the grants);
  • an example of an allowed and a refused rename, and the note that an engine's client (catalog · manage) does all of these;
  • Names match the way the catalog resolves them: case, width forms and invisible characters equated, accents not; grants that differ only in case are the same grant;
  • Refusals: the Iceberg error model, and a table of 403/400/413 with the messages quoted from main.rs and mount.rs at 1e0a3cf8.
  • The limits list KI-311 and KI-312.
• Storage and catalog: the signer sentence now says egret refuses every …/aws/s3/sign request with 403. The setup step links to the new subsection for what needs more than a table grant.
• Catalog and storage errors: six new symptom rows (403 rename, 403 commit, 403 recursive drop, 403 remote signing, 400 malformed body, 413 body cap). A paragraph on the Iceberg JSON refusals, and one on the /config uri without the port (KI-314).
• Tagging: the recursive-drop bullet says only a client with a catalog-level write or manage grant may do it.
• FAQ: a new question, "Why is a catalog client refused a rename or a commit that its grant seems to allow?".
• Upgrade: a version note for #758. It says there is no migration and no API change, and that egret-provisioned engines are not affected. It lists what a narrower client may now be refused, the case-insensitive matching (no wider reach), the JSON refusals and the 1 MiB / 16 MiB caps.
• Known issues: the intro is updated. No row closed; four added:
  • KI-311 (Security, S2, marked high severity): a read-only Catalog Client (table or namespace read) gets vended S3 credentials that write and delete the table's files, also without a delegation header. Measured: a reader made a table unreadable. Scoped to the table's location. Being fixed in the next package; no version promised.
  • KI-312 (Security, S3): create namespace for any write grant; list namespaces for any grant; a table grant lists every table name in its namespace.
  • KI-313 (Security, S3): no body-read timeout on the guarded routes. A client that declares a body and sends nothing holds the connection; memory stays capped, and an unauthenticated client gets 401 at once.
  • KI-314 (Bug, S2): behind the demo edge on a non-default port, /config advertises its uri without the port, which breaks PyIceberg. Cause not confirmed.
• REST API reference: regenerated from platform main's openapi.json with scripts/gen-api-reference.mjs. No diff (#758 has no API shape change), so nothing is committed.

Screenshots

None changed: #758 has no UI change. No re-shoot.

Notes

• KI-311 to KI-314 are the next free numbers after main (KI-310). No docs PR is open.
• The legend has no "high" severity. KI-311 is marked S2 (it has a workaround) and says High severity in its text, matching the platform PR's HIGH.
• Check access is about engine policies, not catalog grants, so it is unchanged.
• The /config row and page note describe what the live check measured on the demo edge (nginx sends X-Forwarded-Host $host). Whether other proxies cause it is not verified.
• Every statement was checked against the guard (crates/egret-bin/src/main.rs) and the mount (crates/egret-catalog-engine/src/mount.rs) at 1e0a3cf8, the spec (D1–D14), and the live-check report.
• English only: the docs repo has no i18n/vi mirror.
• Build: npm run typecheck and npm run build pass locally (en and vi locales; no broken links or anchors reported).

Checklist

• Wording taken from the guard and mount refusals at 1e0a3cf8
• npm run typecheck and npm run build pass
• New rows with the next free IDs (no row described these holes, so none closed)
• REST API reference regenerated (no diff)
• Screenshots: none affected
• No secrets, tokens or real data added

🤖 Generated with Claude Code